EnigmA Amiga Run 1996 February/EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso/earcd/editor/proged10.lha/InstallProgED/sources/DevManual

Text File | 1995-09-02 | 34KB | 1,401 lines

              -----------------------------------------------

                 ProgED V1.0 by Giovanni Lambiase (C) 1995

                         Note per i programmatori

              -----------------------------------------------


-------------------------
 1. Strutture principali
-------------------------

    In questo paragrafo descriveremo tutte le strutture utili per un
utente che indenta scrivere un cliente API. Le strutture PEDWindow e Prefs
descrivono, rispettivamente, le finestre aperte dal ProgED e le preferenze
globali. Seguono altre strutture più piccole ma non meno importanti, come
la struttura che definisce le linee del testo o i programmi interni
(creati dal pannello di programmazione del ProgED). Il commento ad ogni
campo inizia con i caratteri "^--" ).




    struct PEDWindow
    {
    struct Window    *Window;

        ^-- Puntatore alla finestra intuition. Se la finestra è chiusa
            (vedi comando interno FREEZE) vale NULL.

    struct Gadget    *GadgetScrollX,
            *GadgetScrollY,
            *GadgetUpArrow,
            *GadgetDownArrow,
            *GadgetLeftArrow,
            *GadgetRightArrow;

    ^-- Puntatori ai gadget di scorrimento e alle relative frecce.

    struct Image    *ImageUpArrow,
            *ImageDownArrow,
            *ImageLeftArrow,
            *ImageRightArrow;

    ^-- Immagini delle quattro frecce attaccate ai gadget di scroll.

    int         OldSx,
             OldSy,

    ^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
            a sinistra nella finestra PRECEDENTI quelle attuali. Questi valori
            non considerano i fold precedenti che vengono considerati come una
            singola linea.

             Sx,
             Sy;

    ^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
            a sinistra nella finestra ATTUALI. Questi valori non considerano
            i fold precedenti che vengono considerati come una singola linea.

    struct Line    *FirstLine,
            *LastLine;

    ^-- Puntatore alla prima ed alla ultima linea del testo.

    LONG         MaxCol,

    ^-- Copia di Prefs.MaxCol (Num. max di colonne nel testo).

             NumCol,

    ^-- Num. di colonne nella finestra (larghezza in caratteri).

             MaxLine,

    ^-- Num. di linee nel testo (non tiene conto dei fold).

             NumLine;

    ^-- Num. di linee nella finestra (altezza in linee).

    ULONG         Size;

    ^-- Dimensione in byte del testo in memoria.

    WORD         Left,
             Top,
             Width,
             Height;

    ^-- Variabili temporanee. Mantengono le dimensioni e la posizione
            della finestra mentre è chiusa.

    WORD         ZoomInfo[4];

    ^-- Array relativo al gadget Zoom di intuition.

    char         FileName[200];

    ^-- Nome del file (completo) caricato in memoria.

    char         Title[200];

    ^-- In questa zona ProgED costruisce il titolo della finestra.

    LONG         CursorCol;
    LONG         CursorLine;

    ^-- Posizione del cursore nel testo (colonna/linea). Non tiene
            conto dei fold.

    LONG         LastCursorCol;

    ^-- Ultima colonna in cui abbiamo scritto qualcosa.

    struct Line    *Line;

    ^-- Puntatore alla linea su cui si trova il cursore.

    UWORD         RealNumCol;

    ^-- Num colonne reali (numero di bytes,un TAB è pari ad 1).

    UWORD         LogicNumCol;

    ^-- Num colonne logiche (tiene conto degli spazi relativi ai TAB).

    UWORD         FWidth,
             FHeight,

    ^-- Larghezza e altezza (in pixel) del font utilizzato.

             FBase,

    ^-- Baseline del font utilizzato.

             WOffsetX,
             WOffsetY;

    ^-- Offset X ed Y della finestra (dovuto ai bordi sup. e sinistro).

    struct RastPort *RP;

    ^-- Rastport della finestra (Window->RPort).

    UBYTE         Ins;

    ^-- TRUE=modo inserimento,FALSE=modo overwrite.

    UBYTE         MLine,

    ^-- TRUE=blocco con opzione LINE, FALSE=altrimenti.

             Block;

    ^-- Tipo blocco: NO_SEL,BLOCK_SEL,COLBLOCK_SEL (vedi file "Ped.h").

    LONG         BlockLine,
             BlockCol;

    ^-- Inizio blocco marcato (linea e colonna).

    ULONG         Changes;

    ^-- Cambi dall'ultimo salvataggio.

    struct Event     *Events;

    ^-- Puntatore ad un array di strutture Events. Ogni struttura
            mantiene un evento per la coda di UNDO/REDO. Il numero di
            strutture è dato nel successivo campo UndoLevels.

    LONG         LastEvent;

    ^-- Ultimo evento nella coda.

    ULONG         NumEvent,

    ^-- Numero di eventi nella coda.

             NumRedo,

    ^-- Numero di REDO possibili.

             UndoLevels;

    ^-- Lunghezza della coda.

    char        *CuttedLine;

    ^-- Clipboard linea (vedi comando LINE CUT).

    struct Marker    Marker[MAXMARKER];

    ^-- Vettori di marker. Ogni marker detiene una posizione nel testo.

    struct Folder    *Folder;

    ^-- Puntatore ad una lista di folder. Ogni struttura mantiene le
            informazioni relative ad un fold.

    int         LinesFolded;

    ^-- Numero di linee chiuse nei vari fold.

    int         NumFolds;

    ^-- Numero totale di fold.

    UBYTE         Frozen;

    ^-- TRUE=finestra chiusa, FALSE=aperta.

    ULONG         Locked;

    ^-- Se >0 la finestra è bloccata dagli handler.

    ULONG         AutoSave;

    ^-- Contatore autosave (in secondi). Decresce fino a 0.

    struct Line    *OldLine;
    UBYTE        *LineBuffer,
            *Pun,
             InsLine,
             Warn;

    ^-- Dati utili SOLO durante il load dal PED_DISK. Non manipolare.

    UBYTE             OldKeys[MAXTEMPLATE];
    UBYTE             PunOldKeys;

    ^-- Dati utili per i template (ricordano gli ultimi tasti battuti).

    struct DateStamp    DateStamp;

    ^-- Data ultima modifica (utile per gli handler).

    struct PEDWindow    *NextWindow;

    ^-- LINK alla prossima finestra del ProgED.

    ULONG             UserData[16];

    ^-- Dati utente. Se hai bisogno di memorizzare dati per ogni
            finestra utilizza questi campi.
    }




    struct Prefs
    {
    ULONG        ScreenMode;
    UWORD        ScreenWidth;
    UWORD        ScreenHeight;
    UWORD        ScreenOverscanType;
    UBYTE        ScreenDepth;
    UBYTE        ScreenAutoScroll;

    ^-- Caratteristiche dello schermo del ProgED: DisplayID,larghezza,
            altezza,tipo overscan,profondità,flag autoscroll.

    UWORD        ScreenColors[MAXCOLOR];

    ^-- Primi MAXCOLOR colori dello schermo. Tali colori vengono
            memorizzati e salvati da ProgED.

    char        ScreenFontName[MAXFONTNAM+1];
    UWORD        ScreenFontSize;

    ^-- Nome e dimensione del font per lo schermo.

    char        MenuFontName[MAXFONTNAM+1];
    UWORD        MenuFontSize;

    ^-- Nome e dimensione del font per i menù.

    char        TextFontName[MAXFONTNAM+1];
    UWORD        TextFontSize;

    ^-- Nome e dimensione del font per i testi.

    char        GadgetFontName[MAXFONTNAM+1];
    UWORD        GadgetFontSize;

    ^-- Nome e dimensione del font per i gadget. ATTENZIONE solo
            font di dimensione 8 !!!!!!!!!!!!!!!

    UWORD        MaxCol;

    ^-- Numero massimo di colonne per i testi. Ogni finestra, all'apertura,
            copia nel suo omonimo campo questo valore.

    UBYTE        AltStep;

    ^-- Salto righe quando si utilizza il comando UP STEP (o DOWN STEP).

    UBYTE        Tab;

    ^-- Dimensione TAB in caratteri.

    UBYTE        LeftBorder;
    UBYTE        RightBorder;
    UBYTE        TopBorder;
    UBYTE        BottomBorder;

    ^-- Bordi oltre il quale il cursore provoca uno scroll.

    UBYTE        UseKeyWordColors;

    ^-- TRUE=attiva l'uso dei colori per le parole chiavi,FALSE=disabilita.

    UBYTE        KeyAlpha[256];

    ^-- NON MANIPOLARE!!!!!!!!!!!!!!!!!!!!!! Grazie.

    char        **KeyWord;

    ^-- Puntatore al vettore di (char *) contenente le parole.

    int        NumKeyWord;

    ^-- Numero di parole nel vettore.

    char        GestColorOff,
            GestColorOn;

    ^-- Caratteri di disattivazione ed attivazione della gestione.

    UBYTE        UseCommentColors;

    ^-- TRUE=Attiva l'uso dei colori per i commenti,FALSE=disabilita.

    UWORD        CheckColorLines;

    ^-- Max num. di linee di un commento (0=senza limite).

    UBYTE        Comment1Pen,

    ^-- Penna da utilizzare per i commenti tra più linee.

            Comment2Pen;

    ^-- Penna da utilizzare per i commenti fino a fine linea.

    char        Comment1On[MAXCOMMENT+1],
            Comment1Off[MAXCOMMENT+1],

    ^-- Stringhe iniziali e finali dei commenti su più linee.

            Comment2On[MAXCOMMENT+1];

    ^-- Stringa iniziale dei commenti fino a fine linea.

    UBYTE        BackPen;

    ^-- Penna sfondo schermo.

    UBYTE        PaperPen;

    ^-- Penna carta (sfondo finestre).

    UBYTE        DefTextPen;

    ^-- Penna testo.

    UBYTE        PaperBlockPen;

    ^-- Penna blocchi marcati.

    UWORD        ScreenPens[13];

    ^-- Penne intuition dello schermo del ProgED.

    UBYTE        Clipboard;

    ^-- Clipboard standard.

    UBYTE        EraseRight;

    ^-- TRUE=attiva cancellazione spazi e TAB a fine linea.

    UBYTE        ShowCursorPos;

    ^-- TRUE=Mostra la posizione (linea e colonna) del cursore nella
            barra del titolo della finestra.

    UBYTE        ShowPathName;

    ^-- TRUE=Mostra il path completo del file,FALSE=solo il nome.

    UBYTE        AutoArrangeVer;

    ^-- TRUE=Arrangia verticalmente le finestre. Questo flag è
            mutuamente esclusivo col successivo.

    UBYTE        AutoArrangeHor;

    ^-- TRUE=Arrangia orizzontalmente le finestre. Questo flag è
            mutuamente esclusivo col successivo.

    UBYTE        Favourite;

    ^-- TRUE=Favorisci la finestra attiva dandole mezzo schermo.

    UBYTE        UseSetDefPubScr;

    ^-- TRUE=Setta lo schermo del ProgED come schermo pubblico.

    UBYTE        UseClock;

    ^-- TRUE=Attiva l'orologio sullo schermo del ProgED.

    UBYTE        Backup;

    ^-- TRUE=Crea un backup ad ogni salvataggio.

    UBYTE        Save;

    ^-- TRUE=Salvataggio sicuro,FALSE=normale.

    UBYTE        SaveRefs;

    ^-- TRUE=Salva,insieme al file, i riferimenti contenuti nel file
            stesso.

    UBYTE        UnfoldOnGotoMarker;
    UBYTE        UnfoldOnGotoLine;
    UBYTE        UnfoldOnGotoByte;
    UBYTE        UnfoldOnGotoScan;

    ^-- TRUE=Effettua un unfold quando il ProgED salta ad una linea dopo:
            1) un salto ad un marker, 2) un salto ad una linea, 3) un salto
            ad un byte, 4) un salto ad un riferimento

    UBYTE        BlankBorders;

    ^-- TRUE=Elimina i bordi degli schermi (rendili neri).

    UBYTE        AutoFold;

    ^-- TRUE=Auto-fold al caricamento.

    char        SearchFoldFileName[MAXFOLDFUNCNAME+1];

    ^-- Nome della funzione di ricerca dei fold.

    LONG        DefBits;

    ^-- Bits da dare ai file salvati (bisogna effettuare uno XOR con
            0x000F prima di effettuare l'operazione).

    char        DefComment[MAXCOMMENT2+1];

    ^-- Commento da dare ai file salvati.

    UBYTE        CreateIcons;

    ^-- TRUE=Crea icone per i file salvati.

    UBYTE        UseKeyWordInd;

    ^-- TRUE=Abilita l'indentazione automatica.

    char        **KeyWordInd;

    ^-- Puntatore ad un vettore di parole. Ogni parola termina con uno
            dei caratteri IND_xxx che specifica il tipo di indentazione.

    int        NumKeyWordInd;

    ^-- Numero di parole nel vettore.

    UWORD        IndJump;

    ^-- Colonne per livello d'indentazione.

    UBYTE        SeparateItems;

    ^-- TRUE=Separa i menù con una barra.

    struct MyMenu    *Menu;

    ^-- Puntatore ad una lista che definisce i menù.

    char        HelpFile[MAXFILENAME+1];

    ^-- Nome file della guida per i menù.

    struct MyKey    *Key;

    ^-- Puntatore ad una lista che definisce i tasti.

    UBYTE        UseAppIcon;

    ^-- TRUE=Mostra la AppIcon quando sei iconificato.

    UBYTE        UseMenuItem;

    ^-- TRUE=Appendi un item al menù "Strumenti" del WB quando sei
            iconificato.

    UBYTE        UseAutoSave;

    ^-- TRUE=Attiva autosalvataggio.

    UWORD        MinAutoSave;

    ^-- Numero di minuti tra gli autosave.

    UBYTE        AutoReLoad;

    ^-- TRUE=Ricarica, alla partenza, tutti i testi che erano in
            memoria nella sessione precedente.

    UBYTE        MouseBlanker;

    ^-- TRUE=Attiva il mouseblanker.

    UBYTE        FastLoad;

    ^-- TRUE=Attiva il caricamento veloce,FALSE=normale.

    char        **APIClients;

    ^-- Puntatore ad un vettore di (char *). Ogni stringa è il nome
            (su disco) di un cliente API.

    int        NumAPIClients;

    ^-- Numero di stringhe nel vettore precedente (numero clienti API).

    char        StartUpMacro[MAXSTARTUPMACRO];

    ^-- Macro REXX iniziale.

    char        PreIconifyMacro[MAXSTARTUPMACRO];

    ^-- Macro REXX pre-iconificazione.

    char        PostIconifyMacro[MAXSTARTUPMACRO];

    ^-- Macro REXX post-iconificazione.

    struct MyScan    *Scan;

    ^-- Puntatore ad una lista contenente gli scanner attualmente
            caricati.

    struct MyTemplate    *Template;

    ^-- Puntatore ad una lista contenente i template.

    UBYTE        UseTemplate;

    ^-- TRUE=Attiva gestione dei template.

    UBYTE        UseRightGadget;

    ^-- TRUE=Attiva il gadget di scrolling destro.

    UBYTE        UseBottomGadget;

    ^-- TRUE=Attiva il gadget di scrolling inferiore.

    LONG        LeftExtraSpace,
            RightExtraSpace,
            TopExtraSpace,
            BottomExtraSpace;

    ^-- Spazi liberi (in pixel) da lasciare in alto,basso,destra e
            sinistra quando le finestre vengono riaggiustate.

    char        **DictWord;

    ^-- Puntatore ad un vettore di (char *).Ogni stringa è una delle
            frasi presenti nel dizionario.

    int        NumDictWord;

    ^-- Numero di parole nel dizionario.

    UBYTE        UseAutoCase;

    ^-- TRUE=Attiva autocase (aggiusta maius./minus. delle parole
            presenti nel dizionario).

    UBYTE        CheckPar;

    ^-- TRUE=Attiva controllo delle parentesi '(' ')' quando il
            cursore lascia la linea.

    UBYTE        FastMode;

    ^-- TRUE=Attiva modo veloce,FALSE=modo normale.

    char        **Ref;

    ^-- Puntatore ad un vettore di (char *). Ogni stringa contiene un
            pattern o una directory in cui cercare i riferimenti durante
            la creazione della mappa.

    int        NumRef;

    ^-- Numero di stringhe nel vettore precedente.

    UBYTE        RAMReference;

    ^-- TRUE=Mantieni la mappa dei riferimenti in RAM.

    UBYTE        ReferenceCase;

    ^-- TRUE=Ricerca dei riferimenti case-sensitive,FALSE=non case-sen.

    char        ReferenceFile[MAXREFNAME+1];

    ^-- Nome del file contenente la mappa dei riferimenti.

    char        **HuntPath;

    ^-- Puntatore ad un vettore di stringhe. Ogni stringa rappresenta
            una directory in cui ricercare i file quando l'utente attiva
            l'apposito comando.

    int        NumHuntPath;

    ^-- Numero di stringhe presenti nel vettore precedente.

    UBYTE        UseRTSysReq;
    UBYTE        UseRTFileReq;
    UBYTE        UseRTFontReq;
    UBYTE        UseRTScreenReq;

    ^-- TRUE=Usa, rispettivamente, le richieste, i file-requester,
            i font-requester, e i screenmode-requester della ReqTools.library.
            Ponendo a FALSE uno dei flag ProgED utilizza la Asl.library.

    char        **ProjectFiles;

    ^-- Puntatore ad un vettore di stringhe. Ogni stringa è il nome
            di uno dei file nel progetto.

    int        NumProjectFiles;

    ^-- Numero di file nel progetto (numero di stringhe nel vettore
            precedente).

    UWORD        Left,
            Right;

    ^-- Margini sinistro e destro per le operazioni di raggruppamento
            dei blocchi.

    char        XpkLib[5];

    ^-- Nome libreria XPK da utilizzare per i salvataggi con la
            XpkMaster.library.

    UBYTE        XpkMode;

    ^-- Modo XPK da utilizzare per i salvataggi con la XpkMaster.library.

    int        XpkPos;

    ^-- NON MANIPOLARE!!!!!!!!!! Grazie.

    char        XpkPassWord[52];

    ^-- Password per le librerie XPK che la richiedono.

        ULONG        UndoLevels;

    ^-- Numero di livelli di UNDO. Quando ProgED apre una nuova finestra
            copia questo valore nel campo UndoLevels della finestra e crea
            la coda di UNDO della lunghezza data.
    }




    struct Line
    {
    char        *Buffer;

    ^-- Testo della linea (termina con zero)

    struct Line    *PrevLine,
            *NextLine;

    ^-- Puntatori alla linea precedente e successiva del testo

    struct Folder    *Folder;

    ^-- Se questa linea è chiusa in un fold questo puntatore punta
            alla relativa struttura Folder (che si trova nella apposita
            lista presente nella finestra).
    }




    struct MyTemplate
    {
    char             Template[MAXTEMPLATE+1];

    ^-- Stringa che attiva questo template.

    struct MyProgram    *Prg;

    ^-- Programma interno da eseguire all'attivazione.

    struct MyTemplate    *NextTemplate;

    ^-- Puntatore alla prossima struttura della lista.
    }



    struct MyScan
    {
    BPTR         SegList;

    ^-- Puntatore BPTR alla seglist della funzione caricata.

    ULONG        (* ASM ScanFunction)(RG(a0) char *,RG(a1) char *);

    ^-- Puntatore alla funzione assembler contenuta nella seglist
            precedente (è pari all'indirizzo precedente più 4 bytes).

    char         ScanExtension[MAXEXTSCAN+1],

    ^-- Pattern AmigaDOS che individua i file su cui deve operare lo
            scanner.

             Name[MAXSCANNAME+1];

    ^-- Nome (su disco) della funzione.

    struct MyScan    *NextScan;

    ^-- Puntatore alla prossima struttura della lista.
    }




    struct MyProgram
    {
    char            *String,

    ^-- Puntatore alla stringa del comando.

                *Dir,

    ^-- Eventuale directory corrente (solo per TYPE_SHELL/TYPE_AREXX).

                *Output;

    ^-- Eventuale file d'uscita (solo per TYPE_SHELL/TYPE_AREXX).

    UBYTE             Type;

    ^-- Tipo del comando (vedi costanti TYPE_xxxxx).

    UBYTE             Async;

    ^-- TRUE=comando asincrono,FALSE=sincrono. Vale solo per i
            comandi di tipo TYPE_SHELL. è automaticamente TRUE per
            i comandi TYPE_AREXX.

    struct MyProgram    *NextProgram;

    ^-- Puntatore al prossimo comando del programma interno.
    }




    struct MyMenu
    {
    char             Name[MAXMENUNAME+1];

    ^-- Nome di questo menù.

    struct MyItem        *Items;

    ^-- Puntatore alla lista di item relativi a questo menù.

    struct MyMenu        *NextMenu;

    ^-- Puntatore al prossimo menù della lista.
    }

    struct MyItem
    {
    char             Name[MAXMENUNAME+1];

    ^-- Nome di questo item.

    char             Key[MAXMENUNAME+1];

    ^-- Tasto (o stringa) di attivazione di questo item.

    struct MySub        *Subs;

    ^-- Puntatore alla lista di subitem relativi a questo menù.

    struct MyProgram    *Prg;

    ^-- Puntatore al programma interno da eseguire all'attivazione
            di questo item.

    UBYTE             CheckType;    /* NB: DEVE RIMANERE DOPO Prg */

    ^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
            CHECK_xxxx.

    struct MyItem        *NextItem;

    ^-- Puntatore al prossimo item.
    }

    struct MySub
    {
    char             Name[MAXMENUNAME+1];

    ^-- Nome di questo subitem.

    char             Key[MAXMENUNAME+1];

    ^-- Tasto (o stringa) d'attivazione di questo subitem.

    struct MyProgram    *Prg;

    ^-- Programma interno da eseguire all'attivazione del subitem.

    UBYTE             CheckType;    /* NB: DEVE RIMANERE DOPO Prg */

    ^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
            CHECK_xxxx.

    struct MySub        *NextSub;

    ^-- Puntatore al prossimo subitem.
    }




    struct MyKey
    {
    ULONG             Qual,
                 Code;

    ^-- Identificano il tasto a cui rispondere (corrispondono ai campi
            Code e Qualifier di un messaggio intuition).

    struct MyProgram    *Prg;

    ^-- Programma interno da eseguire all'attivazione del tasto.

    struct MyKey        *NextKey;

    ^-- Prossimo tasto nella lista.
    }

    struct Event
    {
    UBYTE         Type;
    UBYTE         Arg1;
    char        *Arg2;
    ULONG         Arg3,
             Arg4,
             Arg5,
             Arg6,
             Arg7;
    LONG         Col,
             Line;
    }

    ^-- Questa struttura è volutamente lasciata senza commento.




    struct Folder
    {
    char         Name[MAXFOLDNAME+1];

    ^-- Nome assegnato dalla funzione di ricerca a questo fold (viene
            mostrato sulla linea che rappresenta il fold stesso).

    long         Num;

    ^-- Numero di linee di cui è composto il fold.

    struct Line    *Line;

    ^-- Linea alla quale si trovava il cursore al momento della
            chiusura.

    long         Col;

    ^-- Colonna alla quale si trovava il cursore al momento della

    struct Line    *Start,
            *End;

    ^-- Linea iniziale e finale del fold.

    struct Folder    *NextFolder;

    ^-- Puntatore al prossimo fold della lista.
    }




    struct Marker
    {
    struct Line    *Line;

    ^-- Puntatore alla linea relativa alla posizione memorizzata. Se la
            linea viene cancellata ProgED porta, automaticamente, questo
            valore a NULL. In questo caso un eventuale salto porta il
            cursore alla prima linea del testo.

    long         Col;

    ^-- Colonna relativa alla posizione memorizzata.
    }




------------
 2. Scanner
------------

    Uno scanner deve essere scritto tramite una funzione assembler o una
funzione C che prende gli argomenti nei registri. Il codice risultante
deve essere linkato SENZA alcun modulo di startup, in modo tale che la
prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:

    A0: Indirizzo della linea su cui effettuare la ricerca. Punta ad una
        stringa terminata con 0.

    A1: Indirizzo del buffer che conterrà il riferimento, se trovato.

    La funzione deve ritornare nel registro D0 la lunghezza della stringa
creata nel buffer puntato da A1. Nel caso la funzione non abbia trovato
nulla deve ritornare 0.

    NOTA: è necessario salvare tutti i registri all'ingresso della
          funzione e ripristarli all'uscita.



-----------
 3. Folder
-----------

    Una funzione di ricerca dei fold deve essere scritta tramite una funzione
assembler o una funzione C che prende gli argomenti nei registri. Il codice
risultante deve essere linkato SENZA alcun modulo di startup, in modo tale
che la prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:

    A0: è l'indirizzo della struttura PEDWindow relativa al testo su
        cui effettuare la ricerca.

    D0: Contiene il numero della colonna su cui è posizionato il cursore.
        (0=prima colonna).

    D1: Contiene il numero della linea su cui è posizionato il cursore.
        Tale numero è assoluto. Ciò significa che non tiene conto dei
        fold eventualmente presenti nel testo. (0=prima linea).

    A1: Contiene l'indirizzo di una long-word. In tale long-word la funzione
        deve scrivere il numero della linea iniziale del fold, se trovato.
        Anche in questo caso la funzione non deve considerare eventuali
        fold già presenti nel testo. (0=prima linea).

    A2: Contiene l'indirizzo di una long-word. In tale long-word la funzione
        deve scrivere il numero della linea finale del fold, se trovato.
        Anche in questo caso la funzione non deve considerare eventuali
        fold già presenti nel testo. (0=prima linea).

    A3: Punta ad un buffer in cui la funzione deve scrivere la stringa
        che ProgED scriverà a fianco dell'indicatore ">FOLD". Generalmente
        il nome della funzione C, ecc.

    La funzione deve ritornare in D0 il valore 1 se ha trovato un fold, 0
altrimenti. Nel primo caso la funzione deve anche fornire, tramite A1 e A2
i numeri di linea iniziali e finali del fold e, tramite A3, la stringa
rappresentante il fold. è necessario,infine, salvare tutti i registri
all'ingresso della funzione e ripristinarli all'uscita.

    NOTA: la funzione 'FOLD ALL' viene eseguita eseguendo una chiamata
alla funzione su tutte le linee (dalla prima all'ultima) e con il
numero di colonna pari a 0 (prima colonna).



----------------
 4. Clienti API
----------------

    ProgED consente ad applicazioni esterne (chiamate "clienti") di
 "agganciarsi" ad esso. Un cliente API è semplicemente un normale
programma (scritto in qualsiasi linguaggio). Tale programma deve
essere scritto in modo tale da "registrarsi" presso il ProgED. Ciò
consente al ProgED di tracciare tutti i clienti e di mandar loro
messaggi sulle operazioni che devono effettuare.

I messaggi che un cliente deve inviare a ProgED (nella sua porta
API di nome "PED_API") hannno la seguente struttura:



    struct APIMessage
    {
        struct Message     am_Message;
        ULONG              am_MsgType,
                           am_MsgArg[10],
                           am_RC;
    }

    am_Message:

         è un campo contenente un messaggio standard Exec.

    am_MsgType:

         Contiene il tipo di messaggio da inviare.

    am_MsgArg[]:

         è un vettore contenente un massimo di 10 argomenti
         dipendenti dal tipo del messaggio

    am_RC:

         è il codice di ritorno che ProgED restituisce al cliente
         per informarlo sul successo dell'operazione.




    I tipi di messaggi che un cliente può spedire a ProgED sono, per ora:

    PED_API_REGISTER:

          Registra un cliente presso ProgED. Richiede un puntatore ad una
          struttura di tipo APIClient in am_MsgArg[0]. Non ritorna nessun
          risultato in am_RC.

    PED_API_UNREGISTER:

          Informa ProgED che il cliente vuole andarsene (!?). Richiede lo
          STESSO puntatore dato al momento della registrazione, con il
          messaggio PED_API_REGISTER, in am_MsgArg[0]. Non ritorna nessun
          risultato in am_RC.

    PED_API_ADD_INTERNAL_COMMAND:

          Consente di espandere le funzionalità del ProgED aggiungendo un
          nuovo comando interno. A tale scopo è necessario allocare e
          riempire una struttura ArexxExtCmds e fornire il suo puntatore
          in am_MsgArg[0]. Nessun risultato in am_RC.

    PED_API_REM_INTERNAL_COMMAND:

          Rimuove un comando precedentemente aggiunto tramite il messaggio
          PED_API_ADD_INTERNAL_COMMAND. è necessario fornire in am_MsgArg[0]
          lo STESSO puntatore dato al momento dell'aggiunta del comando.
          Non ritorna risultati in am_RC.

    PED_API_GET_ACTIVE_WINDOW:

        Ottiene, in am_RC, l'indirizzo della struttura PEDWindow associata
        alla finestra attualmente attiva.

    PED_API_GET_WINDOW_LIST:

        Ottiene, in am_RC, l'indirizzo iniziale della lista di strutture
        PEDWindow corrispondenti ai testi in memoria.

    PED_GET_SCREEN_ADDRESS:

        Ottiene, in am_RC, l'indirizzo dello schermo del ProgED. Se il ProgED
        è attualmente iconificato ritorna NULL.

    PED_GET_PREFS_ADDRESS:

        Ottiene, in am_RC, l'indirizzo della struttura Prefs.

    PED_GET_PUBSCRNAME:

        Ottiene, in am_RC, un puntatore al nome dello schermo pubblico
        aperto dal ProgED.

    NOTA: La struttura ArexxExtCmds (e tutti gli oggetti a cui puntano i
          suoi campi), fornita al momento dell'aggiunta del comando, deve
          rimanere valida in memoria. è possibile riutilizzarla (o
          liberare la memoria associata solo DOPO aver utilizzato un
          messaggio di tipo PED_REM_INTERNAL_COMMAND.
          Lo stesso vale per la struttura APIClient utilizzata per il
          messaggio PED_API_ADD_INTERNAL_COMMAND. In questo caso è
          possibile riutilizzare la struttura dopo il corrispondente
          messaggio PED_API_REM_INTERNAL_COMMAND.




    I messaggi che ProgED può inviare ad un cliente sono, per ora:

    PED_API_SHOW:

        ProgED ha riaperto il suo schermo. L'indirizzo dello schermo
        può essere ottenuto nel campo am_MsgArg[0]. Nel campo am_MsgArg[1],
        invece, si trova un puntatore al nome dello schermo pubblico
        utilizzato. Il cliente puo' utilizzare queste due informazioni
        per aprire eventuali finestre sullo schermo del ProgED. Questo
        messaggio viene spedito solo se, al momento della registrazione,
        il cliente ha settato il flag NOTIFY_ON_SHOWHIDE.

    PED_API_HIDE:

        ProgED stà per chiudere il suo schermo. Questo messaggio viene
        spedito solo se, al momento della registrazione, il cliente ha
        settato il flag NOTIFY_ON_SHOWHIDE.


    PED_API_KEY:

        L'utente ha battuto un tasto. Il cliente può ottenere la struttura
        IntuiMessage relativa leggendo il campo MsgArg[0]. Tale campo
        conterrà il puntatore alla struttura IntuiMessage contenente il
        messaggio di tipo rawkey ricevuto dal ProgED. Questo messaggio
        viene spedito solo se, al momento della registrazione, il cliente
        ha settato il flag NOTIFY_ON_KEY.
        NOTA: In ogni caso, al termine della gestione di questo messaggio,
        ProgED eseguirà l'azione legata al tasto. Inoltre il cliente
        NON DEVE modificare il messaggio stesso, perchè è un messaggio
        proveniente da Intuition!

    PED_API_QUIT:

        ProgED sta per terminare. Alla ricezione di questo messaggio (che
        viene SEMPRE inviato a prescindere dai flag NOTIFY_xxx) il cliente
        deve chiudere le eventuali finestre e terminare. E' VIETATO
        UTILIZZARE LA PORTA API DOPO LA RICEZIONE DI QUESTO MESSAGGIO !!!!!
        Questo implica che, dopo la ricezione di questo messaggio, il
        cliente NON DEVE tentare di togliere la registrazione e/o la
        definizione di comandi esterni.



    Qui di seguito sono riportate le spiegazioni riguardanti i campi delle
diverse strutture utilizzate.


    struct APIClient
    {
        struct MsgPort          *ac_ClientPort;
        ULONG                    ac_Notify;
        char                    *ac_name;
        struct APIClient        *ac_Next;
    }

    ac_ClientPort:

        Indica l'indirizzo di una porta messaggi a cui ProgED invierà i
        messaggi informativi al cliente. Questo tipo di messaggi verrà
        spiegato successivamente.

    ac_Notify:

        Indica quali tipi di messaggi il cliente vuole ricevere dal ProgED.
        Gli unici tipi di messaggi selezionabili attualmente sono indicati
        dal flag NOTIFY_ON_SHOW_HIDE.

    ac_Name:

        Punta al nome del cliente.

    ac_Next:

        Porre a NULL. Conterrà il successore cliente della lista interna
        del ProgED.




    struct ArexxExtCmds
    {
        UBYTE                    External;
        char                    *Name;
        char                    *Template;
        void                    *Defaults[MAXREXXARGS];
        LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
        struct ArexxExtCmds     *NextCmd;
    }

    External:

        Indica che il comando è gestito da un cliente. Porre SEMPRE a TRUE.

    Name:

        Nome del comando. Specificare sempre in lettere maiuscole.

    Template:

        è il template AmigaDOS del comando.

    Default[]:

        Indica il vettore di puntatori che deve essere passato alla
        funzione ReadArgs della dos.library. Deve contenere i valori
        di default dei parametri del template. Per ulteriori informazioni
        leggere la documentazione della funzione ReadArgs.

    CommFunc:

        Indica il puntatore alla funzione che realizza il comando. Tale
        funzione deve essere scritta in assembler (o ricevere i parametri
        come una funzione assembler). Essa deve ricevere un puntatore ad
        una struttura CommandData in A0 e ritornare il codice d'errore
        risultante dall'esecuzione in D0. In seguito analizzeremo la
        struttura CommandData.

    NextCmd:

        Porre a NULL. ProgED ne modificherà il valore portandolo a
        puntare al prossimo comando fornito dallo stesso cliente o da
        un altro.




    struct CommandData
    {
        char              *CommandLine;
        void             **CommandArgs;
        struct MyWindow   *CurrentWindow,
                          *FirstWindow;
        struct Prefs      *CurrentPrefs;
        LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
    }

    CommandLine:

        Punta ad una stringa riportante l'intera linea di comando riguardante
        il comando.

    CommandArgs:

        Punta ad un vettore di (void *). Ogni puntatore deve essere utilizzato
        secondo le norme dettate dalla ReadArgs. Questo vettore, infatti, è
        il risultato della applicazione della stessa funzione alla linea di
        comando (tenendo presente i default dati nella struttura ArexxExtCmds).

    CurrentWindow:

        Indica il puntatore alla struttura PEDWindow indicante la finestra
        attualmente attiva.

    FirstWindow:

        Indica il puntatore alla prima struttura PEDWindow della lista di
        finestre mantenuta dal ProgED.

    ExecuteInternalCommand:

        è un puntatore ad una funzione assembler. Chiamando questa
        funzione (specificando in A0 il puntatore ad una stringa) è
        possibile eseguire i comandi interni del ProgED. A tale scopo
        la stringa puntata da A0 deve contenere la linea di comando
        desiderata. In D0 viene ritornato il codice d'errore risultante.

        NOTA: Non utilizzare la porta ARexx di ProgED per eseguire i
        comandi interni! Così facendo, infatti, si bloccherebbero
        sia ProgED che il cliente. Ciò è dovuto al fatto che, mentre
        ProgED esegue la funzione che implementa il comando, NON PUò
        rispondere ai messaggi provenienti da sè stesso!



-------------------
 5. Funzioni utili
-------------------

    Le funzioni C che seguono sono utili per la scrittura di folder e
scanner. Esse riguardano la ricerca di linee. Potete utilizzarle
tagliandole da questo testo e inserendole nei vostri programmi.



/*****
 *
 * FUNZIONE:    struct Line *SearchLine(struct Line *line,int y)
 *
 * SCOPO:    Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
 *        dalla prima linea del file data da line.
 *        NB: Tiene conto dei FOLDS.
 *
 * RESTITUISCE: Un puntatore alla linea cercata.
 *
 ****/

struct Line *SearchLine(struct Line *line,int y)
{
    while(((y--)>0)&&(line))    line=NextLine(line);
    return(line);
}



/*****
 *
 * FUNZIONE:    int SearchLine2(struct Line *line,int y)
 *
 * SCOPO:    Cerca il # della linea (tenendo conto dei FOLD)
 *        della linea ASSOLUTA y.
 *
 * RESTITUISCE: Il # della linea cercata.
 *
 ****/

int SearchLine2(struct Line *line,int y)
{
    int    n=0;

    while(((y--)>0)&&(line))
    {
        if (!line->Folder)    n++;
        else    if (line->NextLine)
                if (!line->NextLine->Folder)    n++;
        line=line->NextLine;
    }
    if (line)    return(n);
    else        return(0);
}



/*****
 *
 * FUNZIONE:    int SearchLine3(struct Line *first,struct Line *line)
 *
 * SCOPO:    Cerca il # assoluto della linea line a partire
 *        dalla prima linea del file data da first.
 *        NB: NON tiene conto dei FOLDS.
 *
 * RESTITUISCE: Il # della linea cercata.
 *
 ****/

int SearchLine3(struct Line *first,struct Line *line)
{
    long    n=0;

    while(first)
    {
        if (first==line)    break;
        n++;
        first=first->NextLine;
    }
    return(n);
}



/*****
 *
 * FUNZIONE:    struct Line *SearchLine4(struct Line *line,int y)
 *
 * SCOPO:    Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
 *        dalla prima linea del file data da line.
 *        NB: NON tiene conto dei FOLDS.
 *
 * RESTITUISCE: Un puntatore alla linea cercata.
 *
 ****/

struct Line *SearchLine4(struct Line *line,int y)
{
    while(((y--)>0)&&(line))    line=line->NextLine;
    return(line);
}